🕸️ Ada Research Browser

tasks.md
Home›Research Reports›tasks.md
← Back

Tasks: Data Models and Documentation Generation Foundation

Input: Design documents from /specs/001-data-models-docs-foundation/ Prerequisites: plan.md (required), spec.md (required for user stories), research.md, data-model.md, quickstart.md

Tests: Tests are NOT explicitly requested in the feature specification. Test tasks are included for YAML schema validation and integration testing as they are necessary for data integrity and CI/CD validation gates.

Organization: Tasks are grouped by user story to enable independent implementation and testing of each story. Note that User Stories 1-3 are all P1 (critical foundation) and form the core data models. They can be worked on in parallel once the foundational infrastructure is in place.

Format: [ID] [P?] [Story] Description

Path Conventions

This is an Ansible project structure with Python tooling. All paths are from repository root (rcd-cui/).

Phase 1: Setup (Shared Infrastructure)

Purpose: Project initialization and basic structure

Phase 2: Foundational (Blocking Prerequisites)

Purpose: Core infrastructure that MUST be complete before ANY user story can be implemented

⚠️ CRITICAL: No user story work can begin until this phase is complete

Checkpoint: Foundation ready - user story implementation can now begin in parallel

Phase 3: User Story 1 - Establish Single Source of Truth for Control Mappings (Priority: P1) 🎯 MVP

Goal: Create canonical YAML file mapping all 110 NIST 800-171 Rev 2 controls to Rev 3, CMMC Level 2, and NIST 800-53 Rev 5 with complete metadata

Independent Test: Load the control mapping YAML file, verify all 110 NIST 800-171 Rev 2 controls are present with complete metadata, and confirm accurate crosswalk mappings to Rev 3, CMMC Level 2, and 800-53 Rev 5 controls

Implementation for User Story 1

Checkpoint: At this point, User Story 1 should be fully functional and testable independently. Control mapping is the canonical data source for all 110 controls.

Phase 4: User Story 2 - Create Plain-Language Glossary for All Stakeholders (Priority: P1)

Goal: Create machine-readable YAML glossary with 60+ terms, each with plain-language explanations and role-specific context for all 5 audience types

Independent Test: Select any acronym or technical term from compliance documents, look it up in the glossary, and verify that a non-technical reader can understand what it means and why it matters to their role

Implementation for User Story 2

Checkpoint: At this point, User Story 2 should be fully functional. Glossary provides plain-language definitions for all stakeholders.

Phase 5: User Story 3 - Document HPC-Specific Tailoring Decisions (Priority: P1)

Goal: Create structured YAML documenting 10+ HPC/security control conflicts with tailored implementations and compensating controls

Independent Test: Select an HPC-specific scenario (e.g., "session timeout on compute nodes"), find it in the tailoring document, and verify it explains the standard requirement, why HPC conflicts, the tailored implementation, and any compensating controls

Implementation for User Story 3

Checkpoint: At this point, User Story 3 should be fully functional. HPC tailoring decisions are documented with compensating controls.

Phase 6: User Story 4 - Define Organization-Defined Parameters for Rev 3 (Priority: P2)

Goal: Assign specific values to all 49 Organization-Defined Parameters in NIST 800-171 Rev 3, aligned with DoD guidance and adapted for university research computing

Independent Test: Verify all 49 ODPs from NIST 800-171 Rev 3 have assigned values in the YAML file, each with the ODP ID, control reference, parameter description, assigned value, and rationale

Implementation for User Story 4

Checkpoint: At this point, User Story 4 should be fully functional. All 49 ODPs are defined with rationale.

Phase 7: User Story 5 - Generate Audience-Specific Documentation (Priority: P2)

Goal: Implement Python documentation generator that produces 7 distinct outputs from YAML data sources using Jinja2 templates

Independent Test: Run the documentation generator script and verify it produces all 7 output files (pi_guide.md, researcher_quickstart.md, sysadmin_reference.md, ciso_compliance_map.md, leadership_briefing.md, glossary_full.md, crosswalk.csv) with no errors, and confirm that technical jargon is hyperlinked to glossary entries

Implementation for User Story 5

Checkpoint: At this point, User Story 5 should be fully functional. Documentation generator produces all 7 audience-specific outputs.

Phase 8: User Story 6 - Validate Glossary Coverage Across All Project Files (Priority: P3)

Goal: Implement Python glossary validator that scans all project files for undefined acronyms and returns non-zero exit code on violations

Independent Test: Create a test document with a known undefined acronym, run the glossary validator, and verify it flags the undefined term and returns a non-zero exit code

Implementation for User Story 6

Checkpoint: At this point, User Story 6 should be fully functional. Glossary validator enforces "Plain Language First" principle.

Phase 9: User Story 7 - Establish Project Skeleton and Build System (Priority: P2)

Goal: Create complete Ansible project structure, Makefile, and README for operational usability

Independent Test: Clone the repository, run make docs, make validate, and make crosswalk, and verify all commands execute successfully and produce expected outputs

Implementation for User Story 7

Checkpoint: All user stories should now be independently functional. Project skeleton provides operational scaffolding.

Phase 10: Polish & Cross-Cutting Concerns

Purpose: Improvements that affect multiple user stories

Dependencies & Execution Order

Phase Dependencies

User Story Dependencies

Within Each User Story

Parallel Opportunities

Parallel Example: Foundational Phase

# Launch all Pydantic model tasks together:
Task: "Create Pydantic model for FrameworkMapping in scripts/models/control_mapping.py"
Task: "Create Pydantic model for GlossaryTerm in scripts/models/glossary.py"
Task: "Create Pydantic model for HPCTailoringEntry in scripts/models/hpc_tailoring.py"
Task: "Create Pydantic model for ODPValue in scripts/models/odp_values.py"

# Launch all Jinja2 partial tasks together:
Task: "Create Jinja2 template partial for glossary hyperlinking in templates/_partials/glossary_link.j2"
Task: "Create Jinja2 template partial for control table formatting in templates/_partials/control_table.j2"
Task: "Create Jinja2 template partial for standard header in templates/_partials/header.j2"

Parallel Example: User Story 1 (Control Mapping)

# Divide control families across multiple developers:
Developer A: T028-T031 (AC, AT, AU, CA families)
Developer B: T032-T035 (CM, IA, IR, MA families)
Developer C: T036-T039 (MP, PE, PS, RA families)
Developer D: T040-T042 (SA, SC, SI families)

# All work on same file (roles/common/vars/control_mapping.yml) but different sections
# Merge when all complete

Implementation Strategy

MVP First (User Stories 1, 2, 3 Only - All P1)

  1. Complete Phase 1: Setup
  2. Complete Phase 2: Foundational (CRITICAL - blocks all stories)
  3. Complete Phase 3: User Story 1 (Control Mapping)
  4. Complete Phase 4: User Story 2 (Glossary)
  5. Complete Phase 5: User Story 3 (HPC Tailoring)
  6. STOP and VALIDATE: Test all 3 P1 user stories independently
  7. Deploy/demo if ready (core data models complete)

Incremental Delivery

  1. Complete Setup + Foundational → Foundation ready
  2. Add User Stories 1, 2, 3 (P1) → Test independently → Core data models complete (MVP!)
  3. Add User Story 4 (P2 - ODPs) → Test independently → All 4 YAML files ready
  4. Add User Story 5 (P2 - Doc Generator) → Test independently → Documentation automation complete
  5. Add User Story 7 (P2 - Project Skeleton) → Test independently → Operational scaffolding complete
  6. Add User Story 6 (P3 - Glossary Validator) → Test independently → Quality gate complete
  7. Complete Phase 10 (Polish) → Production-ready

Parallel Team Strategy

With multiple developers:

  1. Team completes Setup + Foundational together
  2. Once Foundational is done:
  3. Developer A: User Story 1 (Control Mapping - 110 controls)
  4. Developer B: User Story 2 (Glossary - 60+ terms)
  5. Developer C: User Story 3 (HPC Tailoring - 10+ entries)
  6. Developer D: User Story 7 (Project Skeleton - Makefile, README)
  7. When US 1-4 complete:
  8. Developer E: User Story 5 (Doc Generator - needs all 4 YAML files)
  9. Developer F: User Story 4 (ODPs - 49 parameters)
  10. When US 2 complete:
  11. Developer G: User Story 6 (Glossary Validator - needs glossary)
  12. Stories complete and integrate independently

Notes

Task Summary

Total Tasks: 150 - Phase 1 (Setup): 12 tasks - Phase 2 (Foundational): 10 tasks - Phase 3 (US1 - Control Mapping): 24 tasks - Phase 4 (US2 - Glossary): 16 tasks - Phase 5 (US3 - HPC Tailoring): 18 tasks - Phase 6 (US4 - ODPs): 13 tasks - Phase 7 (US5 - Doc Generator): 18 tasks - Phase 8 (US6 - Glossary Validator): 12 tasks - Phase 9 (US7 - Project Skeleton): 15 tasks - Phase 10 (Polish): 12 tasks

Parallel Opportunities: 67 tasks marked [P] can run in parallel

Independent Test Criteria: - US1: Load YAML, verify 110 controls with complete metadata - US2: Lookup any term, verify plain-language explanation for all 5 audiences - US3: Find HPC scenario, verify tailoring with compensating controls - US4: Verify all 49 ODPs have assigned values with rationale - US5: Run generator, verify 7 outputs with glossary hyperlinks - US6: Run validator with undefined term, verify non-zero exit code - US7: Run make docs/make validate/make crosswalk, verify success

Suggested MVP Scope: User Stories 1, 2, 3 (all P1) = Core data models (control mapping, glossary, HPC tailoring)